
/** A class that performs actions as a path is traced. At every node and link hit
    along the path, an element of the tracer is called. This allows specific data
    to be created as a result of traversing a predefined path. For example, if
    one wanted to create directions from point a to point b, they would create
    a route and then create a TraceStrategy with information on how to format the
    directions.
    @author Ian Helmke, Dan King
*/
public interface TraceStrategy<NI, LI, T> {

  /** Initializes (or reinitializes) this tracer to its default state. This allows
      the same tracer to be used in many different paths, without needing to create
      a new instance of the tracer for each one.
  */
  public void initTracer();

  /** Handles the reciept of a node on a path. Nodes are visited in sequential
      order and may be hit more than once, depending on the path.
      @param node The current node of the route.
  */
  public void handleNode(INode<NI, LI> node);

  /** Handles the reciept of a link on a path. Links are visited in sequential
      order and may be hit more than once, depending on the path.
      @param link The current link of the route.
  */
  public void handleLink(ILink<LI, NI> link);

  /** Returns the result of this tracer, having visited all applicable nodes
      and routes.
      @return The product of type T generated by this TraceStrategy.
  */
  public T returnProduct();
}